LoadDataSource

LoadDataSource(datasource[, createtype[, selectstring]])

Download data from the Target data source to the mobile device and overwrite, append or update table(s) in the local database on the device.

Can also be used to send data from your Digitise app to a Web Service (see Notes below).

All

datasource - required

Specifies the Data Source(s) to be acted on – click here to see how to specify Data Source(s) in this parameter.

You can specify multiple Data Sources separated by commas, e.g. "db1,db2,db3".

Each Data Source which downloads successfully will be updated in the local database even if other Data Sources fail to complete successfully.

 

createtype - optional

String defining whether local data is to be overwritten or not.

Possible values are:

 

selectstring - optional

A SQL Select string to be passed to the App Server to be run against the Target data source where the Target is an ADO database.

If datasource is a Custom Table, this parameter should contain the full Select statement e.g. "SELECT * FROM table1 WHERE user = 'John'". The Select string can start with SELECT or SELECT DISTINCT and columns can be referred to using the format <table>.<column> but <table>.* is not supported. Only Custom Tables where the Mode Property is set to Remote ADO can be updated using LoadDataSource.

In addition, for Custom Tables, the Select string must return the same number of columns and in the same order as defined in the Data Source.

For example, imagine you have a Custom Table Data Source, ds1, with a table, dstable1, which contains fields: dscol1, dscol2 and dscol3. Calling:

LoadDataSource("ds1.dstable1", "create", "SELECT table1.col1, table2.col1, table1.col2 FROM table1,table2 WHERE table1.id = table2.id")

will create a new table every time it is called and will return table1.col1 in dscol1, table2.col1 in dscol2 and table1.col2 in dscol3.

If datasource is an ADO Database Data Source, this parameter should contain only a 'where' clause, excluding the word 'where', e.g. "user = 'John'". Columns can be referred to using the format <table>.<column> but <table>.* is not supported.

In either case, when specifying your SQL Select statement you may want to specify the order in which records should be returned by including an ORDER BY clause, e.g. "SELECT * FROM table1 WHERE user = 'John' ORDER BY table1.userID".

 

If you omit this parameter, all selected columns in the Data Source will be returned unless:

• You have specified a SQL Select statement in a table's Filter or SQL Statement Property. In this case this statement will be used to determine which records to download. The Filter Property applies to ADO Database Data Sources and the SQL Statement Property to Custom Tables which have their Mode Property set to Remote ADO.

• You have used the SetSelectString Method to specify the SQL Select statement to be used to extract records from the remote database. In this case, you must omit the selectstring parameter altogether otherwise it will overwrite the select statement(s) set using SetSelectString. Do not include an empty string for this parameter as this will also overwrite the select statement(s) and download all records.

See Notes below for more information about using the Filter and SQL Statement Properties and SetSelectString Method.

nothing

• For Web Service data sources, LoadDataSource calls the Web Service to download data. The call to the Web Service also includes data to be sent TO the Web Service. This data consists of the current values in any controls that have an output mapping to the Web Service Data Source.

  • The values sent to the Web Service are the current values in the controls and LoadDataSource doesn't read any values from the current record in the local database before sending the data to the Web Service. Any default values you have specified for elements within a Data Source relate solely to the creation of records within the local database and are not automatically entered into controls. Consequently, any controls which have data elements from the Web Service as output mappings must be initialized before this call, especially if you want to input default values for unedited controls. Failure to initialize the output controls before calling this Method will result in an error being generated.

   

  Another way of sending data to a Web Service is via the RefreshControls Method.

  • LoadDataSource can't be used with Web API Data Sources.

• If one or more Target data sources are ADO databases, the selectstring parameter allows you to specify which records should be downloaded from the data sources. However, if you are specifying multiple Data Sources and you specify the selectstring parameter, the same select statement will be applied to all of them.

  You can also specify which records are to be downloaded for each table using the Filter Property for ADO Database Data Sources or the SQL Statement Property for Custom Tables, allowing you to provide a different SQL Select statement for each database if required.

  If the Data Source is a Custom Table, the SQL Statement Property should contain the full Select statement e.g. "SELECT * FROM table1 WHERE user = 'John'". The SELECT statement can start with SELECT or SELECT DISTINCT and columns can be referred to using the format <table>.<column> but <table>.* is not supported. Only Custom Tables where the Mode Property is set to Remote ADO can be updated using LoadDataSource. In addition, the SELECT Statement must return the same number of columns as are defined in the Custom Table and in the order in which you want them to be mapped to the columns in the Custom Table.

  Otherwise, if the Data Source is an ADO Database Data Source, the Filter Property is used and should contain only a 'where' clause, excluding the word 'where', e.g. "user = 'John'". Columns can be referred to using the format <table>.<column> but <table>.* is not supported.

  In either case, when specifying your SQL Select statement you may want to specify the order in which records should be returned by including an ORDER BY clause, e.g. "SELECT * FROM table1 WHERE user = 'John' ORDER BY table1.userID".

  If the Filter or SQL Statement Property for a table is blank all records in that table will be downloaded.

  If the selectstring parameter is included, this will be used in preference to any Select statement specified in the Filter/SQL Statement Property.

  Alternatively, the SetSelectString Method allows you to create a table of Data Sources and specify a Select statement to be used to determine the records downloaded for each Data Source in the list. When you call the LoadDataSource Method, any Data Source listed in the current SetSelectString table will be downloaded using the specified Select string, if there is one. For Data Sources not included in the list, or if no Select statement has been specified, no Select string will be used and all records will be downloaded for that Data Source.

   

  Note:

  • The first call to SetSelectString resets the Data Source list.

  • Subsequent SetSelectString calls add Data Sources to this list.

  • Once LoadDataSource has been called the Data Source list is cleared and LoadDataSource reverts back to its default mode of operation, until another SetSelectString call is made. Note that calls to Synchronise and LoadDatabase will also clear the current list.

   

  Specifying a SQL Select statement using SetSelectString will override any SQL Select statement specified in the Filter/SQL Statement Property. Likewise, specifying the selectstring parameter will take precedence over a SQL statement set using SetSelectString.

  • You can also change a SQL statement specified in the Filter/SQL Statement Property for a Data Source within App Manager. This allows you to change the records to be selected without having to edit and republish your app. To do this display the Properties for the relevant app in App Manager and then use the Data Sources button.

   

• By default, a progress bar is displayed to show the progress of the download and the user can cancel the download whilst it is in progress. The SetApplicationOption Method allows you to reduce or turn off the messages displayed with the progress bar or to replace it with the device's standard busy indicator instead. It also allows you to disable/re-enable the ability to cancel the download.

  If the user cancels the download, the calling Script will continue if data error reporting is OFF and stop and display a Script Error informing the user that they have cancelled the operation if data error reporting is ON. Data error reporting is turned OFF using the SetDataErrorOn Method or On Error GoTo 0 statement and turned ON using the SetDataErrorOff Method or On Error Resume Next statement. If data error reporting is OFF, you can call GetLastDataError or GetLastError after LoadDataSource to check whether the user cancelled the operation.

• The Digitise app will pause and users will not be able to use the app whilst the data transfer takes place. If you are downloading from a remote database and you want to be able to continue to use the app, see the Synchronise Method instead.

• You cannot call this Method if an asynchronous data transfer is already in progress.

• This Method is not relevant for use with Custom Views.

• You cannot use this Method where you have stored data items such as photos and videos to file rather than in a local database table.

• On Android devices, note the following potential issues relating to large data objects, particularly photographs and videos:

  • The uploading of records that contain multiple photo/video fields may fail due to a limitation in SQLite where the records cannot be read in their entirety from the database when the cumulative size of the data that they contain is over a certain size. This limit is undefined but appears to be tied to the version of Android and the amount of memory the device has available.

  • When downloading large binary fields (i.e. photos or videos) on lower power/memory devices the Digitise Apps Client may fail to download some large bitmaps/videos into the application database. An Out Of Memory error message will be displayed. The overall download should complete but some records may not contain the downloaded image/video data, having Null values in the columns where the Out Of Memory issue occurred. This problem may occur where you are trying to download photos/videos taken on one device, with a higher megapixel camera, to another less powerful device.